home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1998 May: Tool Chest / Dev.CD May 98 TC.toast / Tool Chest / Testing & Debugging / General tools / Audit app & dcmd / Src / LogManager.h < prev    next >
Encoding:
C/C++ Source or Header  |  1993-09-17  |  9.5 KB  |  336 lines  |  [TEXT/KAHL]
  1. /*                                    LogManager.h                                */
  2. /*
  3.  * LogManager.h
  4.  * Copyright © 1993 Apple Computer Inc. All rights reserved.
  5.  *
  6.  * These functions manage a logging display for error messages and other text.
  7.  * The log is implemented as a ListManager list that can hold nLogItems. This
  8.  * module is intentionally more-or-less self-contained so it can easily be
  9.  * exported to other applications.
  10.  */
  11. #ifndef THINK_C                /* MPW includes            */
  12. #include <Errors.h>
  13. #include <Script.h>
  14. #include <Types.h>
  15. #include <Resources.h>
  16. #include <QuickDraw.h>
  17. #include <Fonts.h>
  18. #include <Events.h>
  19. #include <Windows.h>
  20. #include <ToolUtils.h>
  21. #include <Memory.h>
  22. #include <Lists.h>
  23. #include <Printing.h>
  24. #endif
  25.  
  26. /*
  27.  * Usage:
  28.  *        ListHandle                    CreateLog(
  29.  *                const Rect                *viewRect,
  30.  *                short                    listFontNumber,
  31.  *                short                    listFontSize,
  32.  *                short                    nLogLines,
  33.  *                Boolean                    hasGrowBox
  34.  *            );
  35.  *    Create a new log display in the current window. To define a log, first
  36.  *    SetPort to the window, and pass viewRect in window coordinates. Returns
  37.  *    NULL on errors. if nLogLines is zero, a default value (128) will be used.
  38.  *    Note: the log will be displayed with a horizontal and vertical scrollbar.
  39.  *    Be sure to dimension the viewRect to leave room for both: they are not
  40.  *    included in the viewRect (for compatibility with other ListManager calls).
  41.  *    If hasGrowBox is FALSE and the bottom edge of the viewRect does not coincide
  42.  *    with the bottom edge of the window's portRect, the list height will be
  43.  *    adjusted (shrunk) to show an integral number of text lines.
  44.  *
  45.  *        void                        DisposeLog(
  46.  *                ListHandle                logListHandle
  47.  *            );
  48.  *    Dispose of the log. logListHandle may be NULL without disasterous results.
  49.  *
  50.  *        Boolean                        DoClickInLog(
  51.  *                ListHandle                logListHandle,
  52.  *                const EventRecord        *eventRecord
  53.  *            );
  54.  *    Called on a mouse-down in the log viewRect. Returns FALSE if the mouse-down
  55.  *    wasn't in the viewRect (this isn't really an error, but lets you call
  56.  *    DoClickInLog on all mouseDown's). Note: the port should be set to the log
  57.  *    window. You cannot select text in the log. This is a limitation:
  58.  *    Copy to the Clipboard would be useful.
  59.  *
  60.  *        void                        UpdateLog(
  61.  *                ListHandle                logListHandle
  62.  *            );
  63.  *    Called on update events in the log window. UpdateLog passes the window
  64.  *    visRgn to the List Manager.
  65.  *
  66.  *        void                        UpdateLogWindow(
  67.  *                ListHandle                logListHandle
  68.  *            );
  69.  *    Called to update the log area without an update event. This may be used
  70.  *    after displaying a dialog or alert that might have obscured the window.
  71.  *
  72.  *        void                        ActivateLog(
  73.  *                ListHandle                logListHandle,
  74.  *                Boolean                    activating
  75.  *            );
  76.  *    Called on activate, deactivate, suspend and resume events.
  77.  *
  78.  *        void                        MoveLog(
  79.  *                ListHandle                logListHandle,
  80.  *                short                    leftEdge,
  81.  *                short                    topEdge
  82.  *            );
  83.  *    Called to move the log within the window (after resizing the window)
  84.  *    LeftEdge and topEdge are in window coordinates.
  85.  *
  86.  *        void                        SizeLog(
  87.  *                ListHandle                logListHandle,
  88.  *                short                    newWidth,
  89.  *                short                    newHeight
  90.  *            );
  91.  *    Resize the log area (after resizing the window). NewWidth and NewHeight
  92.  *    are in window coordinates.
  93.  *
  94.  * The following calls display data in the log.
  95.  *
  96.  *        void                        LogStatus(
  97.  *                ListHandle                logListHandle,
  98.  *                OSErr                    theError,
  99.  *                ConstStr255Param        infoText
  100.  *            );
  101.  *    If theError is not noErr, display the error value and infoText in the log.
  102.  *
  103.  *        void                        DisplayLogString(
  104.  *                ListHandle                logListHandle,
  105.  *                ConstStr255Param        theString
  106.  *            );
  107.  *    Display the argument string in the log.
  108.  *
  109.  *
  110.  * File I/O
  111.  *
  112.  *        OSErr                        SaveLogFile(
  113.  *                ListHandle                logListHandle,
  114.  *                ConstStr255Param        dialogPromptString,
  115.  *                ConstStr255Param        defaultFileName,
  116.  *                OSType                    creatorType
  117.  *            );
  118.  *    Prompt the user for a file name and write the current log contents
  119.  *    to the chosen file. Returns an error status (noErr is ok). This function
  120.  *    returns userCanceledErr if the user cancelled the SFPutFile dialog.
  121.  *
  122.  *        OSErr                        CreateLogFile(
  123.  *                ListHandle                logListHandle,
  124.  *                OSType                    creatorType,
  125.  *                ConstStr255Param        fileName,
  126.  *                short                    vRefNum
  127.  *            );
  128.  *    Create a log on the specified file and volume. Normally, called only
  129.  *    by SaveLogFile.
  130.  *
  131.  *        void                        WriteCurrentLog(
  132.  *                ListHandle                logListHandle
  133.  *            );
  134.  *    Write the current log to the file. This is called when the log file
  135.  *    is first created.
  136.  *
  137.  *        void                        WriteLogLine(
  138.  *                ListHandle                logListHandle,
  139.  *                ConstStr255Param        theText
  140.  *            );
  141.  *    Write a single line of text to the currently-open log, if any.
  142.  *    Any errors are stored in the INFO structure. WriteLogLine is
  143.  *    called to "dribble" new text into the log file.
  144.  *
  145.  *        OSErr                        CloseLogFile(
  146.  *                ListHandle                logListHandle
  147.  *            );
  148.  *    Close the currently active log file (if any). Returns the earliest
  149.  *    status (i.e., if the disk filled during a "dribble" operation, it
  150.  *    will return a device full error).
  151.  *
  152.  *        OSErr                        GetLogFileError(
  153.  *                ListHandle                logListHandle
  154.  *            );
  155.  *    Return the last file error stored in the log record.
  156.  *
  157.  *        Boolean                        HasLogFile(
  158.  *                ListHandle                logListHandle
  159.  *            );
  160.  *    TRUE if a log file is currently open.
  161.  *
  162.  * This function prints the log
  163.  *
  164.  *        OSErr                        PrintLog(
  165.  *                ListHandle                logListHandle,
  166.  *                THPrint                    hPrint,
  167.  *                short                    fontNumber,
  168.  *                short                    fontSize
  169.  *            );
  170.  *    Print the current contents of the log. if hPrint is non-null, it will
  171.  *    be used to configure the printer. Otherwise, a Print Handle will be
  172.  *    allocated (and disposed) internally. No page numbers or headers or
  173.  *    other useful stuff. Sorry.
  174.  */
  175.  
  176. /*
  177.  * This record is stored in the userHandle variable in the list. The values are
  178.  * needed to specify the font, limit the number of error log lines that are stored,
  179.  * and preserve the log area color. We also hide the horizontal scrollbar here
  180.  * because, if we leave it in the ListRecord, the ListManager will decide to
  181.  * permanently un-hilite it.
  182.  *
  183.  * Note: the LogInfoRecord is private to the LogManager routines.
  184.  */
  185. typedef struct LogInfoRecord {
  186.         ControlHandle        hScroll;
  187.         short                logLines;
  188.         short                fontNumber;
  189.         short                fontSize;
  190.         RGBColor            foreColor;
  191.         RGBColor            backColor;
  192.         short                logFileRefNum;        /* Non-zero if log file open    */
  193.         short                logFileVRefNum;        /* Log file volume refNum        */
  194.         OSErr                logFileStatus;        /* noError or last log file err    */
  195. } LogInfoRecord, *LogInfoPtr, **LogInfoHdl;
  196.  
  197. /*
  198.  * CreateLog
  199.  *        Create a new log display in the current window. To define a log, first
  200.  *        SetPort to the window, and pass viewRect in window coordinates. Returns
  201.  *        NULL on errors. if nLogLines is zero, a default value (128) will be used.
  202.  *        Note: the log will be displayed with a horizontal and vertical scrollbar.
  203.  *        Be sure to dimension the viewRect to leave room for both.
  204.  */
  205. ListHandle                            CreateLog(
  206.         const Rect                        *viewRect,
  207.         short                            listFontNumber,
  208.         short                            listFontSize,
  209.         short                            nLogLines,
  210.         Boolean                            hasGrowBox
  211.     );
  212. /*
  213.  * DisposeLog
  214.  *        Dispose of the log. logListHandle may be NULL.
  215.  */
  216. void                                DisposeLog(
  217.         ListHandle                        logListHandle
  218.     );
  219. /*
  220.  * DoClickInLog
  221.  *        Call on a mouse-down in the log viewRect. Returns FALSE if the mouse-down
  222.  *        wasn't in the viewRect (this isn't really an error, but lets you call
  223.  *        DoClickInLog on all mouseDown's). Note: the port should be set to the log
  224.  *        window. You cannot select text in the log.
  225.  */
  226. Boolean                                DoClickInLog(
  227.         ListHandle                        logListHandle,
  228.         const EventRecord                *eventRecord
  229.     );
  230. /*
  231.  * UpdateLog
  232.  *        Call on update events in the log window.
  233.  */
  234. void                                UpdateLog(
  235.         ListHandle                        logListHandle
  236.     );
  237. /*
  238.  * UpdateLogWindow
  239.  *        Call to force an update on the log's window. This may be used after
  240.  *        displaying a dialog or alert that might have obscured the window.
  241.  */
  242. void                                UpdateLogWindow(
  243.         ListHandle                        logListHandle
  244.     );
  245. /*
  246.  * ActivateLog
  247.  *        Call on activate, suspend, and resume events.
  248.  */
  249. void                                ActivateLog(
  250.         ListHandle                        logListHandle,
  251.         Boolean                            activating
  252.     );
  253. /*
  254.  * MoveLog
  255.  *        Move the log area within the window.
  256.  */
  257. void                                MoveLog(
  258.         ListHandle                        logListHandle,
  259.         short                            leftEdge,
  260.         short                            topEdge
  261.     );
  262. /*
  263.  * SizeLog
  264.  *        Change the size of the log area.
  265.  */
  266. void                                SizeLog(
  267.         ListHandle                        logListHandle,
  268.         short                            newWidth,
  269.         short                            newHeight
  270.     );
  271. /*
  272.  * LogStatus
  273.  *        Call with an error status code and some text to display.
  274.  */
  275. void                                LogStatus(
  276.         ListHandle                        logListHandle,
  277.         OSErr                            theError,
  278.         const StringPtr                    infoText
  279.     );
  280. /*
  281.  * DisplayLogString
  282.  *        Call with some text to display.
  283.  */
  284. void                                DisplayLogString(
  285.         ListHandle                        logListHandle,
  286.         const StringPtr                    theString
  287.     );
  288. StringHandle                        GetLogStringHandle(
  289.         ListHandle                        logListHandle,
  290.         short                            theRow
  291.     );
  292. /*
  293.  * Log file functions.
  294.  */
  295. OSErr                                SaveLogFile(
  296.         ListHandle                        logListHandle,
  297.          ConstStr255Param                dialogPromptString,
  298.         ConstStr255Param                defaultFileName,
  299.         OSType                            creatorType
  300.     );
  301.  
  302. OSErr                                CreateLogFile(
  303.         ListHandle                        logListHandle,
  304.         OSType                            creatorType,
  305.         ConstStr255Param                fileName,
  306.         short                            vRefNum
  307.     );
  308. void                                WriteCurrentLog(
  309.         ListHandle                        logListHandle
  310.     );
  311. void                                WriteLogLine(
  312.         ListHandle                        logListHandle,
  313.         ConstStr255Param                theText
  314.     );
  315. OSErr                                CloseLogFile(
  316.         ListHandle                        logListHandle
  317.     );
  318. OSErr                                GetLogFileError(
  319.         ListHandle                        logListHandle
  320.     );
  321. Boolean                                HasLogFile(
  322.         ListHandle                        logListHandle
  323.     );
  324. /*
  325.  * Print the log.
  326.  */
  327. OSErr                                PrintLog(
  328.         ListHandle                        logListHandle,
  329.         THPrint                            hPrint,
  330.         short                            fontNumber,
  331.         short                            fontSize
  332.     );
  333.  
  334.  
  335.  
  336.